// API: 公告相关接口
import { apiClient } from '@/utils/require'

/**
 * 公告类型定义
 */
export interface AnnouncementUser {
  id: number
  username: string
  email?: string
}

export interface Announcement {
  id: number
  title: string
  content: string
  time: string
  user?: AnnouncementUser
  user_name?: string
}

export interface PaginatedResponse<T> {
  count: number
  next: string | null
  previous: string | null
  results: T[]
}

/**
 * 公告管理API
 * 
 * API说明：
 * - 基础路径：/api/announcements/
 * - 认证方式：Token认证（除登录外所有接口需要）
 * - 权限控制：
 *   - 查看公告：所有已认证用户
 *   - 发布公告：仅教师及以上权限
 *   - 修改/删除：仅创建人或管理员
 */
export const announcementAPI = {
  /**
   * 获取公告列表
   * 
   * 接口：GET /api/announcements/
   * 权限：已认证用户
   * 
   * @param params 查询参数
   * @param params.page 页码（从1开始）
   * @param params.page_size 每页数量（默认10）
   * @param params.search 搜索关键词（支持标题、内容搜索）
   * @param params.ordering 排序字段（默认 '-time'，时间倒序；可用：'time', '-time'）
   * 
   * @returns 分页的公告列表
   * @example
   * // 获取第1页，每页20条，按时间倒序
   * announcementAPI.getAnnouncementList({ page: 1, page_size: 20, ordering: '-time' })
   */
  getAnnouncementList: (params?: {
    page?: number
    page_size?: number
    search?: string
    ordering?: string  // 默认 '-time'（时间倒序）
  }) => {
    return apiClient.get<PaginatedResponse<Announcement>>('/announcements/', { params })
  },

  /**
   * 获取公告详情
   * 
   * 接口：GET /api/announcements/{id}/
   * 权限：已认证用户
   * 
   * @param id 公告ID
   * @returns 公告完整信息（包含标题、内容、发布时间、发布人）
   */
  getAnnouncementDetail: (id: number) => {
    return apiClient.get<Announcement>(`/announcements/${id}/`)
  },

  /**
   * 发布公告
   * 
   * 接口：POST /api/announcements/
   * 权限：仅教师及以上权限可发布
   * 
   * @param data 公告数据
   * @param data.title 公告标题（必填，最大255字符）
   * @param data.content 公告内容（必填，富文本）
   * 
   * @returns 创建成功的公告信息
   * @example
   * announcementAPI.createAnnouncement({ 
   *   title: '期末考试通知', 
   *   content: '本学期期末考试时间为...' 
   * })
   */
  createAnnouncement: (data: { title: string; content: string }) => {
    return apiClient.post('/announcements/', data)
  },

  /**
   * 更新公告（完整更新）
   * 
   * 接口：PUT /api/announcements/{id}/
   * 权限：仅创建人或管理员可更新
   * 
   * @param id 公告ID
   * @param data 完整的公告数据（需包含所有字段）
   * @returns 更新后的公告信息
   */
  updateAnnouncement: (id: number, data: Partial<Announcement>) => {
    return apiClient.put(`/announcements/${id}/`, data)
  },

  /**
   * 部分更新公告（推荐使用）
   * 
   * 接口：PATCH /api/announcements/{id}/
   * 权限：仅创建人或管理员可更新
   * 
   * @param id 公告ID
   * @param data 需要更新的字段（仅传需要修改的字段即可）
   * @returns 更新后的公告信息
   * @example
   * // 仅更新标题
   * announcementAPI.patchAnnouncement(1, { title: '新标题' })
   */
  patchAnnouncement: (id: number, data: Partial<Announcement>) => {
    return apiClient.patch(`/announcements/${id}/`, data)
  },

  /**
   * 删除公告
   * 
   * 接口：DELETE /api/announcements/{id}/
   * 权限：仅创建人或管理员可删除
   * 
   * @param id 公告ID
   * @returns 204 No Content（删除成功）
   */
  deleteAnnouncement: (id: number) => {
    return apiClient.delete(`/announcements/${id}/`)
  }
}

export default announcementAPI
